跳转至

Python 邮件解析中的字节与 Unicode 混淆问题剖析

文章背景与核心概要

将旧版的 Python 2 脚本迁移到 Python 3 时，常常会引入一些与字符串类型相关的隐蔽 Bug。本文详细记录了一个独特的邮件解析问题：当把预解码的 Unicode 字符串（而不是原始字节）传入 email.parser.Parser.parsestr() 时，会导致“双重解码”（Double-Decoding），从而产生夹杂着神秘 U+FFFF 替换字符的损坏文本。

文章深入分析了该问题的根本原因——由于 Python 3 在标准输入中自动对 8bit 传输编码的文本进行了预解码，导致后续解析器将其再次当作字节处理并触发错误。最终的解决方案是改用 email.parser.BytesParser，并通过 sys.stdin.buffer 在字节级别处理标准输入，从而彻底规避此类类型混淆。

背景：(N)MH 中的邮件处理

Background: Email Handling in (N)MH

“离我上次发现在 Python 3 中因为字节/Unicode 混淆问题而‘搬起石头砸了自己的脚’已经过去‘0’天了，尽管这次犯错的方式异常富有创造力且极其隐蔽（即：它没有抛出异常，而是生成了损坏的文本）。” — 发布在 Fediverse

“It has been '0' days since I discovered that I shot myself in the foot in Python 3 with a bytes/Unicode confusion issue, although this one was an unusually creative and subtle way to get things wrong (ie, it had no exceptions, it generated corrupted text).” — On the Fediverse

我使用历史悠久的 (N)MH 来处理电子邮件。尽管功能强大，但 NMH 需要进行一些辅助设置，才能在回复时正确引用 MIME 编码的邮件——具体来说，需要一个程序来对你希望引用的每一个基于文本的正文部分进行 MIME 解码和美化打印。

我为此任务编写了一个长期运行的 Python 程序，最近我将其从 Python 2 迁移到了 Python 3（这个过程带来了许多宝贵的经验教训）。

I handle my email using the venerable (N)MH. While powerful, NMH requires some auxiliary setup to properly quote MIME-encoded email in replies—specifically, a program that MIME-decodes and pretty-prints every text-based body part you wish to quote.

I have a long-standing Python program for this task, which I recently migrated from Python 2 to Python 3 (a process that brought several learning experiences).

症状：神秘的 U+FFFF 字符

The Symptom: Mysterious U+FFFF Characters

最近，我回复的几封邮件开始出现异常，引用的正文中随机散落着渲染为反白 ? 字形的 Unicode 字符。

Recently, several emails I replied to started showing up with Unicode characters rendered as a reverse-video ? glyph scattered randomly throughout the quoted body.

经过调查，这些字符被证实是 U+FFFF。然而，我所回复的原始邮件看起来完全正常。我经过了一番深入挖掘，才发现自己是如何无意中破坏了整个处理流水线的。

Upon investigation, these turned out to be U+FFFF characters. However, the original messages I was replying to appeared completely normal. It took some digging to uncover how I had accidentally sabotaged my own pipeline.

根本原因：通过 Parser.parsestr() 进行双重解码

The Root Cause: Double-Decoding via Parser.parsestr()

我的 MIME 正文解码器通过命令行参数接收 Content-Type 和 Content-Transfer-Encoding，并通过标准输入（由 NMH 的工作方式决定）摄入原始的 MIME 正文文本。

My MIME body part decoder receives the Content-Type and Content-Transfer-Encoding via command-line arguments and ingests the raw MIME body text via standard input (dictated by how NMH operates).

为了解析正文部分，我采用了直观的方法： 1. 构造一个 email.parser.Parser。 2. 读取标准输入以获取 MIME 部分的正文。 3. 将一组最简 MIME 头部与正文组装在一起。 4. 将结果直接传给 Parser.parsestr()。

To parse the body part, I implemented the intuitive approach: 1. Construct an email.parser.Parser. 2. Read standard input to get the body of the MIME part. 3. Assemble a minimal set of MIME headers alongside the body. 4. Pass the result directly to Parser.parsestr().

这种方法的缺陷在于 Python 3 在数据摄入期间处理字符串类型的方式。

The flaw in this approach lies in how Python 3 handles string types during ingestion.

故障剖析

The Breakdown

  1. 输入（The Input）： 被回复的邮件具有 text/plain; charset=utf-8 的内容类型、8bit 的内容传输编码，并且包含范围在 U+0080 到 U+00FF 之间的 Unicode 码点（具体来说，是我的老冤家 U+00A0）。
  2. 不匹配（The Mismatch）： 由于传输编码是 8bit，这些字符在通过 sys.stdin 传入的原始输入中直接表现为 UTF-8 字节。
  3. 陷阱（The Trap）： 当我直接作为文本从 sys.stdin 读取它们时，Python 3 很“贴心”地将流解码为 UTF-8，在我解码出的 Unicode 字符串内部重新生成了 U+00A0 字符。
  4. 双重解码（The Double-Decode）： 随后，我将这个已经解码过的字符串（我把它当作原始的 UTF-8 实体对待）传给了 Parser.parsestr()。解析器试图再次进行 UTF-8 解码（实际上是将我字符串中的 Unicode 码点当作原始字节来处理），在其 U+00A0 码点所在的位置遇到了无效的 UTF-8 序列，并为每个失败的序列插入了一个 U+FFFF 标记。
  1. The Input: The replied-to messages had a content-type of text/plain; charset=utf-8, a content-transfer-encoding of 8bit, and contained Unicode codepoints in the range U+0080 through U+00FF (specifically, my old nemesis U+00A0).
  2. The Mismatch: Because the transfer encoding was 8bit, these characters were represented directly as UTF-8 bytes in the raw input passed via sys.stdin.
  3. The Trap: When I read them directly from sys.stdin as text, Python 3 helpfully decoded the stream as UTF-8, recreating the U+00A0 characters inside my decoded Unicode string.
  4. The Double-Decode: I then passed this already-decoded string—which I treated as a raw UTF-8 entity—into Parser.parsestr(). The parser attempted to decode UTF-8 again (effectively treating the Unicode codepoints in my string as raw bytes), encountered invalid UTF-8 sequences where those U+00A0 codepoints lived, and inserted a U+FFFF marker for each failure.

(注：如果你对 U+00FF 以上的码点犯这个错误，Parser.parsestr() 最终会返回 \u20ac 风格的转义字符，从而使底层错误变得更加明显。)

(Note: If you make this mistake with codepoints above U+00FF, Parser.parsestr() will eventually return \u20ac-style escapes, making the underlying error much more obvious.)

解决方案

The Solution

正确的方法是从 email.parser.Parser 切换到 email.parser.BytesParser 及其 parsebytes() 方法。

The correct approach is to switch from email.parser.Parser to email.parser.BytesParser and its parsebytes() method.

通过使用 sys.stdin.buffer 以原始二进制模式读取标准输入，一切都将对齐：原始二进制数据被直接交给了负责解码原始二进制数据的组件。

By reading standard input in raw binary mode via sys.stdin.buffer, everything aligns correctly: raw binary data is handed directly to the component responsible for decoding raw binary data.

为什么这个问题没有立即暴露出来？ 这个 Bug 严格要求内容传输编码（content-transfer-encoding）为 8bit 而不是 7bit。如果该 MIME 部分已被清洗为 7bit，sys.stdin 中就不会存在原始的 UTF-8 字节供 Python 提前解码为 Unicode 码点。

Why didn't this surface immediately? This bug strictly required a content-transfer-encoding of 8bit rather than 7bit. Had the MIME part been cleaned down to 7bit, there would have been no raw UTF-8 bytes in sys.stdin for Python to prematurely decode into Unicode codepoints.

边栏：代码追踪

Sidebar: Tracing the Code

如果你在这些条件下将 email.parser.Parser 与 Unicode 字符串配合使用：

If you use email.parser.Parser with a Unicode string under these conditions:

  1. 生成的 email.message.EmailMessage 对象会将你的 Unicode 字符串直接存储在其私有属性 ._payload 中。
  2. 调用 .get_content() 会触发策略系统（policy system），进而回调 .get_payload(decode=True)。
  3. 这会使用类似 'str.encode("raw-unicode-escape")' 的方式将你的 Unicode 字符串转换为字节串（bytestring），把 U+00FF 以上的 Unicode 值转换为 \uNNNN 转义形式，同时将 U+0080 到 U+00FF 的字符保留为原始单字节。
  4. 最后，该字节串会通过 'bytes.decode("utf-8", errors="replace")' 进行处理，从而将原始的 \xa0 字节替换为替换字符 U+FFFF。
  1. The resulting email.message.EmailMessage object stores your Unicode string directly inside its ._payload private attribute.
  2. Calling .get_content() triggers the policy system, which calls back to .get_payload(decode=True).
  3. This converts your Unicode string into a bytestring using something akin to 'str.encode("raw-unicode-escape")', transforming Unicode values above U+00FF into \uNNNN escapes while leaving U+0080 through U+00FF as raw single bytes.
  4. Finally, this bytestring is processed via 'bytes.decode("utf-8", errors="replace")', which replaces the raw \xa0 byte with the replacement character U+FFFF.

更多参考信息，请查看 email/contentmanager.py 和 email/message.py（以及第 1137 行）中的实现细节——把这些笔记留在这里，希望我（最好）永远不需要第三次去研究它。

For further reference, check out the implementation details in email/contentmanager.py and email/message.py (and line 1137)—notes left here so I (hopefully) never have to research this a third time.